feat(codex): preserve opt-in provider-host circuit follow-up - #1039

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Scope the failover statement to account cooldowns in every provider configuration page.

Each failover row says that the failures do not affect “cooldowns.” The following circuit row says that the same failures open a 30-second provider-origin cooldown. Replace the unqualified term with account-scoped wording.

• docs-site/src/content/docs/reference/configuration/providers.md#L25-L26: Change “cooldowns” to “account cooldowns.”
• docs-site/src/content/docs/ja/reference/configuration/providers.md#L24-L25: Use the equivalent account-scoped term in Line 24.
• docs-site/src/content/docs/ko/reference/configuration/providers.md#L24-L25: Use the equivalent account-scoped term in Line 24.
• docs-site/src/content/docs/ru/reference/configuration/providers.md#L25-L26: Use the equivalent account-scoped term in Line 25.
• docs-site/src/content/docs/zh-cn/reference/configuration/providers.md#L24-L25: Use the equivalent account-scoped term in Line 24.

As per path instructions and the PR objective, the documentation must distinguish account failover state from the provider-host circuit state.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs-site/src/content/docs/reference/configuration/providers.md` around lines
25 - 26, Update the failover description beside upstreamFailoverThreshold in all
five listed provider configuration
files—docs-site/src/content/docs/reference/configuration/providers.md lines
25-26, docs-site/src/content/docs/ja/reference/configuration/providers.md lines
24-25, docs-site/src/content/docs/ko/reference/configuration/providers.md lines
24-25, docs-site/src/content/docs/ru/reference/configuration/providers.md lines
25-26, and docs-site/src/content/docs/zh-cn/reference/configuration/providers.md
lines 24-25—to replace “cooldowns” with the equivalent account-scoped wording
“account cooldowns,” while leaving the provider-host circuit description
unchanged.

Source: Path instructions

📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win

Extract the shared circuit eligibility predicate and the 503 builder.

This block duplicates policy that already exists in src/server/responses/core.ts:

• eligibility: lines 316-326 here restate preAuthUpstreamHostCircuitKey (src/server/responses/core.ts lines 252-261) as an inline ternary.
• 503 response: lines 335-340 here restate upstreamHostCircuitOpenResponse (src/server/responses/core.ts lines 263-270), and lines 420-425 restate it a third time.

The two eligibility expressions already differ. preAuthUpstreamHostCircuitKey adds route.provider.adapter !== "openai-responses"; this one relies on the enclosing supportsNativeResponsesCompactEndpoint guard at line 312 instead. The current behavior is equivalent, but a future change to circuit eligibility must now be applied in two places written in two different shapes. A change applied to only one place would silently diverge the Responses and compact circuits for the same provider host.

Export both helpers from a shared module and call them from both handlers.

-function preAuthUpstreamHostCircuitKey(route: RouteResult, config: OcxConfig): string | null {
+export function preAuthUpstreamHostCircuitKey(
+  route: Pick<RouteResult, "provider" | "providerName" | "codexAccountMode" | "codexAccountId">,
+  config: OcxConfig,
+  options: { requireResponsesAdapter?: boolean } = {},
+): string | null {
   if (
     normalizeUpstreamHostCircuitThreshold(config.upstreamHostCircuitThreshold) === 0
     || route.codexAccountMode !== "pool"
     || route.codexAccountId !== undefined
     || route.provider.authMode !== "forward"
-    || route.provider.adapter !== "openai-responses"
+    || (options.requireResponsesAdapter !== false && route.provider.adapter !== "openai-responses")
   ) return null;
   return upstreamHostHealthKey(route.providerName, safeOriginLabel(route.provider.baseUrl ?? ""));
 }

-function upstreamHostCircuitOpenResponse(retryAfterSeconds: number): Response {
+export function upstreamHostCircuitOpenResponse(retryAfterSeconds: number): Response {

-    const preAuthCompactHostKey = normalizeUpstreamHostCircuitThreshold(
-      config.upstreamHostCircuitThreshold,
-    ) > 0
-      && route.codexAccountMode === "pool"
-      && route.codexAccountId === undefined
-      && route.provider.authMode === "forward"
-      ? upstreamHostHealthKey(
-        route.providerName,
-        safeOriginLabel(route.provider.baseUrl ?? ""),
-      )
-      : null;
+    // The enclosing supportsNativeResponsesCompactEndpoint() guard already
+    // restricts this path to the canonical backends, so the adapter check
+    // from the Responses path is redundant here.
+    const preAuthCompactHostKey = preAuthUpstreamHostCircuitKey(route, config, {
+      requireResponsesAdapter: false,
+    });
     let compactHostAdmissionLease: UpstreamHostAdmissionLease | null = null;
     let authCtx: CodexAuthContext = { kind: "main", accountId: null };
     if (preAuthCompactHostKey) {
       const admission = acquireUpstreamHostAdmission(
         preAuthCompactHostKey,
         config.upstreamHostCircuitThreshold,
       );
       if (admission.kind === "blocked") {
-        return formatErrorResponse(
-          503,
-          "upstream_host_circuit_open",
-          "Provider host is temporarily unavailable",
-          { retryAfter: String(admission.retryAfterSeconds) },
-        );
+        return upstreamHostCircuitOpenResponse(admission.retryAfterSeconds);
       }
       compactHostAdmissionLease = admission.lease;
     }

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/server/responses/compact.ts` around lines 316 - 343, Extract the shared
upstream-host circuit eligibility predicate and 503 response builder currently
defined in core.ts, export them, and replace the inline ternary and
blocked-admission response in the compact handler with those helpers. Apply the
same response-builder substitution to the later blocked-admission path around
the existing compact handler logic, while preserving the compact endpoint’s
current eligibility behavior and using the shared helpers from both handlers.

🗄️ Data Integrity & Integration | 🔵 Trivial | ⚡ Quick win

Make the no-account-selection assertion observable.

These tests prove that the blocked request sends no upstream request and creates no account-health record. They do not prove that the blocked request skips Pool account selection.

A regression could select pool-b, then return 503 before fetch. The current assertions would still pass. Add an account-selection spy or a before-and-after assertion on Pool affinity or quota state for the second request in both tests.

The supplied routing context places host admission before resolveCodexAuthContext in src/server/responses/compact.ts (Lines 258-417) and defines the eligible pre-auth route in src/server/responses/core.ts (Lines 252-261). The tests should protect that contract.

As per path instructions and the routing objective, this regression test must verify the no-account-selection behavior, not only the no-send outcome.

Also applies to: 962-988

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/responses-compaction-routing.test.ts` around lines 936 - 960, Add an
observable assertion that the second blocked request in both circuit tests skips
Pool account selection, such as spying on the account-selection method or
comparing Pool affinity/quota state before and after that request. Keep the
existing no-send and health assertions, and ensure the test specifically
verifies host admission prevents resolveCodexAuthContext/account selection
before returning 503.

Source: Path instructions

📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add a regression test for the lease key mismatch guard.

The suite covers generation fencing, explicit-null settlement, and unleased observational writes. It does not cover the key mismatch guard.

Two source paths depend on that guard:

• src/codex/upstream-host-health.ts line 253: if (!entry || opts.lease.key !== key) return;
• src/codex/upstream-host-health.ts line 307: if (!entry || lease.key !== key) return false;

Both callers rely on it. src/server/responses/core.ts line 1817 and src/server/responses/compact.ts line 405 detect a host change after admission and return 502. If the key equality check regressed, a lease acquired for host A could settle health for host B, and the circuit state for B would become wrong while A kept a leaked lease. No current test would fail.

Add a focused case near the stale-completion tests.

+  test("a lease cannot settle a different host key", () => {
+    const keyA = upstreamHostHealthKey("openai", "https://chatgpt.com");
+    const keyB = upstreamHostHealthKey("openai", "https://api.openai.com");
+    const leaseA = admit(keyA, 1, 10_000);
+
+    expect(resetUpstreamHostHealth(keyB, leaseA, 10_001)).toBe(false);
+    recordUpstreamHostFailure(keyB, {
+      code: "ECONNREFUSED",
+      now: 10_002,
+      threshold: 1,
+      lease: leaseA,
+    });
+    expect(getUpstreamHostHealth(keyB)).toBeNull();
+
+    // Lease A is still unsettled and retains authority over its own key.
+    recordUpstreamHostFailure(keyA, {
+      code: "ECONNREFUSED",
+      now: 10_003,
+      threshold: 1,
+      lease: leaseA,
+    });
+    expect(getUpstreamHostHealth(keyA)).toMatchObject({
+      consecutiveFailures: 1,
+      cooldownUntil: 10_003 + UPSTREAM_HOST_CIRCUIT_COOLDOWN_MS,
+    });
+  });

As per path instructions, "A behavior change in src/ should come with a focused regression test near the existing tests for that subsystem."

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/upstream-host-circuit.test.ts` around lines 142 - 173, Add a focused
regression test near the existing stale-completion tests that admits a lease for
one upstream-host health key, then attempts both failure recording and reset
against a different key using that lease. Assert the mismatched-key operations
do not mutate the target host’s state, and preserve coverage for both lease
validation paths used by recordUpstreamHostFailure and resetUpstreamHostHealth.

Source: Path instructions